home *** CD-ROM | disk | FTP | other *** search
/ Chip 2005 June / ccd0605.iso / Software / Freeware / Programare / highlight / highlight-W32GUI-2.2-10b-Setup.exe / {app} / README.txt < prev    next >
Text File  |  2005-02-10  |  12KB  |  357 lines
  1. --------------------------------------------------------------------------------
  2. ---  HIGHLIGHT MANUAL (W32 GUI) - Version 2.2-8 -------------- FEBRUARY 2005 ---
  3. --------------------------------------------------------------------------------
  4.  
  5. OSI Certified Open Source Software
  6.  
  7.  
  8. Highlight converts sourcecode to HTML, XHTML, RTF, LaTeX, TeX, XSL-FO and XML 
  9. files with syntax highlighting. Its language definitions, colour themes and
  10. indentation schemes are customizable.
  11.  
  12.  
  13. CONTENT:
  14. --------------------------------------------------------------------------------
  15.  
  16. 1. Platforms
  17. 2. Supported programming/markup languages
  18. 3. Features
  19. 4. Highlight file format
  20. 5. Defining new language definitions
  21. 6. Defining new colour themes
  22. 7. Defining new indentation schemes
  23. 8. Windows Explorer integration
  24. 9. Contact
  25.  
  26.  
  27. 1. PLATFORMS:
  28. --------------------------------------------------------------------------------
  29.  
  30. Highlight is written in C++. There exist three versions of Highlight:
  31. - UNIX console application
  32. - Win32 console application
  33. - Win32 GUI application
  34.  
  35. For other platforms, see the highlight homepage. The source package is known to
  36. compile with gcc3.x, MS Visual .NET, and MW Codewarrior 8.
  37.  
  38.  
  39. 2. SUPPORTED PROGRAMMING / MARKUP LANGUAGES:
  40. --------------------------------------------------------------------------------
  41.  
  42. Currently, Highlight supports the following programming languages, markup
  43. languages and configuration files:
  44.  
  45. Action Script, ADA 95, Agda, AMPL, Aspect, Assembler, Amtrix, Avenue, (G)AWK,
  46. Bash, BlitzBasic, BibTex, BMS, C, C++, C#, ClearBasic, Clipper, Cobol, Coldfusion
  47. MX, CSS, DOS-Batch, Eiffel, Erlang, Euphoria, Express, Felix, Fortran, Frink,
  48. Haskell, HTML, httpd.conf, Icon, IDL, INI, IO, Jasmin, Java, JavaScript, JSP,
  49. LaTeX, LDIF, Lisp, Lotos, Lotus Script, Lua, Make,Maya, Matlab, Maple, Modelica,
  50. Modula 3, Nasal, OCaml, (Object) Pascal, Objective C, Paradox, PATROL, Perl,
  51. PHP, Pike, PL/1, PL/SQL, PostScript, POV Ray, Progress, Prolog, Python, Relax
  52. NG Compact, Rexx, RPM Spec, Ruby, Small, SML, SNMPv2, Spin, Squirrel, Sybase, 
  53. VHDL, Visual Basic, XML.
  54.  
  55.  
  56. 3. FEATURES:
  57. --------------------------------------------------------------------------------
  58.  
  59. - highlighting of keywords, types, strings, numbers, escape sequences, comments,
  60.   symbols and directive lines
  61. - highlighting of custom keyword classes
  62. - coloured output in HTML, XHTML 1.1, RTF, TeX, LaTeX, XSL-FO and XML format
  63. - customizable reformatting and indentation of C, C++, C# and Java source code
  64. - wrapping of long lines
  65. - output of line numbers
  66. - choice to embed the CSS-definitions in the output (X)HTML file or to save them
  67.   in a separate CSS-file
  68. - 50 colour themes
  69. - conversion of plain text to a given output format without highlighting
  70.  
  71.  
  72. 4. HIGHLIGHT FILE FORMAT
  73. --------------------------------------------------------------------------------
  74.  
  75. All Highlight configuration files are stored in plain ASCII text files. The
  76. format is simple:
  77.  
  78. $ParamName=ParamValue
  79.  
  80. ParamName is the identifier of the parameter, ParamValue is its value.
  81. The parameter names are not case sensitive.
  82. The value may be a single character or a list of words. Lists may be split in
  83. multiple lines.
  84.  
  85. Comments start with # as the first character in a line.
  86.  
  87.  
  88. 5. DEFINING NEW LANGUAGE DEFINITIONS:
  89. --------------------------------------------------------------------------------
  90.  
  91. A language definition is a text file, where keywords and symbols of a program-
  92. ming language are assigned to several categories.
  93. Save the new file in the highlight directory/langDefs* with the following name:
  94.  
  95. <usual extension of sourcecode files>.lang
  96.  
  97. Examples: PHP -> php.lang, Java -> java.lang
  98.  
  99. If there exist multiple suffixes, list them in extensions.conf*.
  100.  
  101. FILE FORMAT:
  102.  
  103. # List of keywords; <class> is the name of the keyword class
  104. # The class must be defined in the applied colour theme to provide a matching
  105. # highlighting style
  106. $KW_LIST(<class>)=<List>
  107.  
  108. # Prefix which determines keywords
  109. # The class must be defined in the applied colour theme to provide a matching
  110. # highlighting style
  111. $KW_PREFIX(<class>)=<Character>
  112.  
  113. # Delimiters for keywords
  114. # The class must be defined in the applied colour theme to provide a matching
  115. # highlighting style
  116. $KW_DELIM(<class>)=<open close>
  117.  
  118. # Tag open and close delimiters
  119. # Tags are formatted like keywords of specified class
  120. $TAG_DELIM(<class>)=<tag_open tag_close>
  121.  
  122. # List of String delimiters
  123. $STRINGDELIMITERS=<List>
  124.  
  125. # List of escape characters in Strings (ie. "\")
  126. $ESCCHAR=<List>
  127.  
  128. # Prefix which disables highlighting of escape characters
  129. # within the following string
  130. $RAWSTRINGPREFIX=<Character>
  131.  
  132. # Delimiters of multi-line comments
  133. $ML_COMMENT=<comment_begin comment_close>
  134.  
  135. # List of strings which start single line comments
  136. $SL_COMMENT=<List>
  137.  
  138. # Set true if single line comments have to start in first coloumn
  139. $FL_COMMENT=<true / false>
  140.  
  141. # Opening string of preprocessor directive lines
  142. $DIRECTIVE=<prefix>
  143.  
  144. # Set true if language source code may be reformatted (only C-style languages!)
  145. $REFORMATTING=<true / false>
  146.  
  147. # Symbols which should be coloured (brackets, operators  etc)
  148. $SYMBOLS=<List>
  149.  
  150. # List of special characters which may occour in keywords
  151. $ALLOWEDCHARS=<character list>
  152.  
  153. # Set to true if multiple line comments may be nested
  154. $ALLOWNESTEDCOMMENTS=false
  155.  
  156. # Set to true if programming language is not case sensitive
  157. $IGNORECASE=<true / false>
  158.  
  159. # Include another language definition stored in the same data directory
  160. $INCLUDE=<language definition>
  161.  
  162.  
  163. Example:
  164.  
  165. #Content of pas.lang (Pascal/Objekt Pascal)
  166.  
  167. $KW_LIST(kwa)=true false if else then nil maxint case goto label and div downto in
  168. mod not of or packed with do for do repeat while to until procedure function
  169. program begin end const var type unit interface implementation uses private
  170. public
  171.  
  172. $KW_LIST(kwb)=array boolean char integer file pointer real set string text record
  173.  
  174. $STRINGDELIMITERS=" '
  175. $SL_COMMENT=//
  176. $ML_COMMENT={ }
  177. $IGNORECASE=true
  178.  
  179.  
  180. 6. DEFINING NEW THEME DEFINITIONS
  181. --------------------------------------------------------------------------------
  182.  
  183. Colour themes are stored in plain ASCII files, defining the formatting of the
  184. output. The RTF output ignores the background colour attribute. The files have
  185. to be stored as *.style in the highlight directory/themes*. 
  186.  
  187. FILE FORMAT:
  188.  
  189. #<ColourAttr> = RR GG BB
  190. #RR GG BB describes the red/green/blue hex-values which define the colour.
  191. #(Value range: 00 (none) - FF (full))
  192.  
  193. #<FormatAttr> = <bold> <italic> <underline>
  194. #Bold, italic und underline are optional attributes and may be combined.
  195.  
  196. # Colour of unrecognized text
  197. $DEFAULTCOLOUR=RR GG BB
  198.  
  199. # Background colour (ignored by RTF)
  200. $BGCOLOUR=RR GG BB
  201.  
  202. # Font size
  203. $FONTSIZE=<number>
  204.  
  205. # Formatting of keywords, which belong to the corresponding keyword class
  206. $KW_CLASS(<class>)=<ColourAttr> ( <FormatAttr> )
  207.  
  208. # Formatting of numbers
  209. $NUMBER=<ColourAttr> ( <FormatAttr> )
  210.  
  211. # Formatting of escape characters
  212. $ESCAPECHAR=<ColourAttr> ( <FormatAttr> )
  213.  
  214. # Formatting of strings
  215. $STRING=<ColourAttr> ( <FormatAttr> )
  216.  
  217. # Formatting of strings within compiler directives
  218. $STRING_DIRECTIVE=<ColourAttr> ( <FormatAttr> )
  219.  
  220. # Formatting of comments
  221. $COMMENT=<ColourAttr> ( <FormatAttr> )
  222.  
  223. # Formatting of single line comments
  224. $SL-COMMENT=<ColourAttr> ( <FormatAttr> )
  225.  
  226. # Formatting of compiler directives
  227. $DIRECTIVE=<ColourAttr> ( <FormatAttr> )
  228.  
  229. # Formatting of symbols (optional, equals to $DEFAULTCOLOUR if omitted)
  230. $SYMBOL=<ColourAttr> ( <FormatAttr> )
  231.  
  232. # Formatting of line numbers
  233. $LINE=<ColourAttr> ( <FormatAttr> )
  234.  
  235.  
  236. Example:
  237.  
  238. # Golden.style
  239. $DEFAULTCOLOUR=dd bb 00
  240. $BGCOLOUR=00 00 00
  241. $FONTSIZE=10
  242. $KW_CLASS(kwa)=dd bb 00 bold
  243. $KW_CLASS(kwb)=dd bb 00
  244. $NUMBER=ff ff ff
  245. $ESCAPECHAR=ff 00 00
  246. $STRING=ff 00 00
  247. $STRING_DIRECTIVE=ff 00 00
  248. $COMMENT=97 83 45 italic
  249. $DIRECTIVE=ff dd aa
  250. $LINE=97 83 45
  251.  
  252.  
  253. 7.  DEFINING NEW INDENTATION SCHEMES
  254. --------------------------------------------------------------------------------
  255.  
  256. You can define custom indentation and formatting schemes. To enable reformatting
  257. for your programming language, a $REFORMATTING=true switch has to be added to
  258. the language definition. Note that the Artistic Style parser was designed to
  259. only handle C-style languages (C++, Java, C#) correctly.
  260. Indentation schemes are stored as *.indent in the highlight dir/indentSchemes*.
  261.  
  262. FILE FORMAT:
  263.  
  264. # Brackets handling:
  265. # "break":  Break brackets from pre-block code (i.e. ANSI C/C++ style).
  266. # "attach": Attach brackets to pre-block code (i.e. Java/K&R style).
  267. # "linux":  Break definition-block brackets and attach command-block brackets.
  268. # "break-closing-headers": Break brackets before closing headers (e.g. 'else',
  269. #                          'catch', ..).  Should be appended to $brackets=attach
  270. #                          or $brackets=linux.
  271. $BRACKETS=<break | attach | linux | break-closing-headers>
  272.  
  273. # Insert empty lines around unrelated blocks, labels, classes, ...
  274. # "true": default mode
  275. # "all": also insert empty lines around closing headers
  276. #        (e.g. 'else', 'catch', ...).
  277. $BREAK-BLOCKS=<true | false | all>
  278.  
  279. # Break 'else if()' statements into two different lines.
  280. $BREAK-ELSEIFS=<true / false>
  281.  
  282. # Add extra indentation entire blocks (including brackets).
  283. $INDENT-BLOCKS=<true / false>
  284.  
  285. # Add extra indentation to '{' and '}' block brackets.
  286. $INDENT-BRACKETS=<true / false>
  287.  
  288. # Indent 'case XXX:' lines, so that they are flush with
  289. # their bodies.
  290. $INDENT-CASES=<true / false>
  291.  
  292. # Indent 'class' blocks, so that the inner 'public:', 'protected:' and 'private:'
  293. # headers are indented in relation to the class block.
  294. $INDENT-CLASSES=<true / false>
  295.  
  296. # Indent labels so that they appear one indent less than the current indentation
  297. # level, rather than being flushed completely to the left (which is the default).
  298. $INDENT-LABELS=<true / false>
  299.  
  300. # Indent the contents of namespace blocks.
  301. $INDENT-NAMESPACES=<true / false>
  302.  
  303. # Indent multi-line #define statements
  304. INDENT-PREPROCESSOR=<true / false>
  305.  
  306. # Indent using <num> spaces per indent. Not specifying <num>  will result in a
  307. # default  of 4 spacec per indent.
  308. $INDENT-SPACES=<num>
  309.  
  310. # Indent 'switch' blocks, so that the inner 'case XXX:' headers are indented in
  311. # relation to the switch block.
  312. $INDENT-SWITCHES=<true / false>
  313.  
  314. # Indent a Java source file
  315. $JAVA-STYLE=<true / false>
  316.  
  317. # Indent a maximal <num> spaces in a continuous statement, relatively to the
  318. # previous line.
  319. $MAX-INSTATEMENT-INDENT=<num>
  320.  
  321. # Indent a minimal <num> spaces in a continuous conditional belonging to a
  322. # conditional header.
  323. $MIN-CONDITIONAL-INDENT=<num>
  324.  
  325. # Surround symbols with whitespace:
  326. # "paren": Insert space paddings around parenthesies only
  327. # "oper":  Insert space paddings around operators only.
  328. # "all":   Insert space paddings around operators AND parenthesies.
  329. $PAD=<paren | oper | all>
  330.  
  331.  
  332. Example:
  333.  
  334. # K&R indentation scheme
  335. $indent-brackets=false
  336. $indent-spaces=4
  337. $brackets=attach
  338. $indent-classes=false
  339. $indent-switches=false
  340. $indent-namespaces=false
  341.  
  342.  
  343.  
  344. 8. WINDOWS EXPLORER INTEGRATION
  345. --------------------------------------------------------------------------------
  346.  
  347. Create a link to WinHighlight.exe in the SendTo folder of your Windows home
  348. directory. Now you can right-click your source files, and add them to the
  349. Highlight file listbox during startup in the "Send to" pull down menu.
  350.  
  351.  
  352. 9. CONTACT:
  353. --------------------------------------------------------------------------------
  354.  
  355. AndrΘ Simon
  356. andre.simon1@gmx.de
  357. http://www.andre-simon.de/